Validação de Server Actions no React: Um Guia Completo para Processamento de Entradas de Formulário e Segurança

A introdução das React Server Actions marcou uma mudança de paradigma significativa no desenvolvimento full-stack com frameworks como o Next.js. Ao permitir que componentes de cliente invoquem diretamente funções do lado do servidor, podemos agora construir aplicações mais coesas, eficientes e interativas com menos código repetitivo. No entanto, essa nova e poderosa abstração traz uma responsabilidade crítica para o primeiro plano: validação de entrada e segurança robustas.

Quando a fronteira entre cliente e servidor se torna tão fluida, é fácil ignorar os princípios fundamentais da segurança web. Qualquer entrada vinda de um usuário não é confiável e deve ser rigorosamente verificada no servidor. Este guia oferece uma exploração abrangente do processamento e validação de entradas de formulário dentro das React Server Actions, cobrindo tudo, desde princípios básicos até padrões avançados e prontos para produção que garantem que sua aplicação seja amigável ao usuário e segura.

O que Exatamente São as React Server Actions?

Antes de mergulhar na validação, vamos recapitular brevemente o que são as Server Actions. Em essência, são funções que você define no servidor, mas que podem ser executadas a partir do cliente. Quando um usuário envia um formulário ou clica num botão, uma Server Action pode ser chamada diretamente, contornando a necessidade de criar manualmente endpoints de API, lidar com requisições `fetch` e gerenciar estados de carregamento/erro.

Elas são construídas sobre a base dos formulários HTML e da API `FormData` da Plataforma Web, tornando-as progressivamente aprimoradas por padrão. Isso significa que seus formulários funcionarão mesmo que o JavaScript falhe ao carregar, proporcionando uma experiência de usuário resiliente.

Exemplo de uma Server Action básica:

            // app/actions.js
'use server';

export async function createUser(formData) {
  const name = formData.get('name');
  const email = formData.get('email');

  // ... lógica para salvar o usuário no banco de dados
  console.log('Criando usuário:', { name, email });
}

// app/page.js
import { createUser } from './actions';

export default function UserForm() {
  return (
    

      
      
      Criar Usuário
    
  );
}
            

              
                Copy
              
            
          

Essa simplicidade é poderosa, mas também esconde a complexidade do que está acontecendo. A função `createUser` está sendo executada exclusivamente no servidor, mas é invocada a partir de um componente de cliente. Essa linha direta com a sua lógica de servidor é precisamente por isso que a validação não é apenas um recurso — é um requisito.

A Importância Inabalável da Validação

No mundo das Server Actions, cada função é um portão aberto para o seu servidor. A validação adequada atua como o guarda nesse portão. Eis por que é inegociável:

• Integridade dos Dados: Seu banco de dados e o estado da aplicação dependem de dados limpos e previsíveis. A validação garante que você não armazene endereços de e-mail malformados, strings vazias onde deveriam estar nomes, ou texto num campo destinado a números.
• Experiência do Usuário (UX) Aprimorada: Usuários cometem erros. Mensagens de erro claras, imediatas e específicas ao contexto os guiam para corrigir suas entradas, reduzindo a frustração e melhorando as taxas de conclusão de formulários.
• Segurança Sólida: Este é o aspecto mais crítico. Sem a validação do lado do servidor, sua aplicação fica vulnerável a uma série de ataques, incluindo:
  • Injeção de SQL: Um ator mal-intencionado poderia enviar comandos SQL num campo de formulário para manipular seu banco de dados.
  • Cross-Site Scripting (XSS): Se você armazenar e renderizar entradas de usuário não sanitizadas, um invasor poderia injetar scripts maliciosos que são executados nos navegadores de outros usuários.
  • Negação de Serviço (DoS): Enviar dados inesperadamente grandes ou computacionalmente caros poderia sobrecarregar os recursos do seu servidor.

Validação do Lado do Cliente vs. Lado do Servidor: Uma Parceria Necessária

É importante entender que a validação deve acontecer em dois lugares:

1. Validação do Lado do Cliente: Esta é para a UX. Ela fornece feedback instantâneo sem uma viagem de ida e volta à rede. Você pode usar atributos simples de HTML5 como `required`, `minLength`, `pattern`, ou JavaScript para verificar formatos enquanto o usuário digita. No entanto, ela pode ser facilmente contornada desativando o JavaScript ou usando ferramentas de desenvolvedor.
2. Validação do Lado do Servidor: Esta é para a segurança e integridade dos dados. É a fonte de verdade final da sua aplicação. Não importa o que aconteça no cliente, o servidor deve revalidar tudo o que recebe. As Server Actions são o lugar perfeito para implementar essa lógica.

Regra de ouro: use a validação do lado do cliente para uma melhor experiência do usuário, mas sempre confie apenas na validação do lado do servidor para a segurança.

Implementando Validação em Server Actions: Do Básico ao Avançado

Vamos construir nossa estratégia de validação, começando com uma abordagem simples e avançando para uma solução mais robusta e escalável usando ferramentas modernas.

Abordagem 1: Validação Manual e Retorno de Estado

A maneira mais simples de lidar com a validação é adicionar declarações `if` dentro da sua Server Action e retornar um objeto indicando sucesso ou falha.

            // app/actions.js
'use server';

import { redirect } from 'next/navigation';

export async function createInvoice(formData) {
  const customerName = formData.get('customerName');
  const amount = formData.get('amount');

  if (!customerName || customerName.trim() === '') {
    return { success: false, message: 'O nome do cliente é obrigatório.' };
  }

  if (!amount || isNaN(Number(amount)) || Number(amount) <= 0) {
    return { success: false, message: 'Por favor, insira um valor válido maior que zero.' };
  }

  // ... lógica para criar a fatura no banco de dados
  console.log('Fatura criada para', customerName, 'com o valor', amount);
  
  redirect('/dashboard/invoices');
}
            

              
                Copy
              
            
          

Essa abordagem funciona, mas tem uma grande falha de UX: requer um recarregamento completo da página para exibir a mensagem de erro. Não conseguimos mostrar facilmente a mensagem na própria página do formulário. É aqui que entram os hooks do React para Server Actions.

Abordagem 2: Usando `useFormState` para Tratamento de Erros Contínuo

O hook `useFormState` foi projetado especificamente para este propósito. Ele permite que uma Server Action retorne um estado que pode ser usado para atualizar a UI sem um evento de navegação completo. É a pedra angular do tratamento moderno de formulários com Server Actions.

Vamos refatorar nosso formulário de criação de faturas.

Passo 1: Atualize a Server Action

A action agora precisa aceitar dois argumentos: `prevState` e `formData`. Ela deve retornar um novo objeto de estado que o `useFormState` usará para atualizar o componente.

            // app/actions.js
'use server';

import { revalidatePath } from 'next/cache';
import { redirect } from 'next/navigation';

// Define a forma do estado inicial
const initialState = {
  message: null,
  errors: {},
};

export async function createInvoice(prevState, formData) {
  const customerName = formData.get('customerName');
  const amount = formData.get('amount');
  const status = formData.get('status');

  const errors = {};
  if (!customerName || customerName.trim().length < 2) {
    errors.customerName = 'O nome do cliente deve ter pelo menos 2 caracteres.';
  }
  if (!amount || isNaN(Number(amount)) || Number(amount) <= 0) {
    errors.amount = 'Por favor, insira um valor válido.';
  }
  if (status !== 'pending' && status !== 'paid') {
    errors.status = 'Por favor, selecione um status válido.';
  }

  if (Object.keys(errors).length > 0) {
    return {
      message: 'Falha ao criar a fatura. Por favor, verifique os campos.',
      errors,
    };
  }

  try {
    // ... lógica para salvar no banco de dados
    console.log('Fatura criada com sucesso!');
  } catch (e) {
    return {
      message: 'Erro no Banco de Dados: Falha ao criar a fatura.',
      errors: {},
    };
  }

  // Revalida o cache para a página de faturas e redireciona
  revalidatePath('/dashboard/invoices');
  redirect('/dashboard/invoices');
}

            

              
                Copy
              
            
          

Passo 2: Atualize o Componente do Formulário com `useFormState`

No nosso componente de cliente, usaremos o hook para gerenciar o estado do formulário и exibir os erros.

            // app/ui/invoices/create-form.js
'use client';

import { useFormState } from 'react-dom';
import { createInvoice } from '@/app/actions';

const initialState = {
  message: null,
  errors: {},
};

export function CreateInvoiceForm() {
  const [state, dispatch] = useFormState(createInvoice, initialState);

  return (
    

      

        Nome do Cliente
        
        {state.errors?.customerName && 
          
{state.errors.customerName}
}
      
      
      

        Valor
        
        {state.errors?.amount && 
          
{state.errors.amount}
}
      

      {/* ... outros campos ... */}

      {state.message && 
{state.message}
}
      
      Criar Fatura
    
  );
}
            

              
                Copy
              
            
          

Agora, quando o usuário envia um formulário inválido, a Server Action é executada, retorna o objeto de erro e o `useFormState` atualiza a variável `state`. O componente é renderizado novamente, exibindo as mensagens de erro específicas logo ao lado dos campos correspondentes — tudo sem um recarregamento de página. Isso é uma enorme melhoria na UX!

Abordagem 3: Aprimorando a UX com `useFormStatus`

O que acontece enquanto a Server Action está em execução? O usuário pode clicar no botão de envio várias vezes. Podemos fornecer feedback usando o hook `useFormStatus`, que nos dá informações sobre o status do último envio de formulário.

Importante: `useFormStatus` deve ser usado num componente que seja filho do elemento `

            // app/ui/submit-button.js
'use client';

import { useFormStatus } from 'react-dom';

export function SubmitButton() {
  const { pending } = useFormStatus();

  return (
    
      {pending ? 'Criando...' : 'Criar Fatura'}
    
  );
}

// No seu componente CreateInvoiceForm:
import { SubmitButton } from './submit-button';

// ...

  {/* ... campos do formulário ... */}
  

            

              
                Copy
              
            
          

Com esta simples adição, o botão de envio agora ficará desabilitado e mostrará "Criando..." enquanto o servidor estiver processando a requisição, prevenindo envios duplicados e dando um feedback claro ao usuário.

Abordagem 4: Validação de Nível de Produção com Zod

Verificações manuais com `if` são adequadas para formulários simples, mas para aplicações complexas, elas se tornam verbosas, propensas a erros e difíceis de manter. É aqui que bibliotecas de validação de esquema como Zod, Yup ou Valibot se destacam.

Zod é uma biblioteca de declaração e validação de esquemas focada em TypeScript. Ela permite que você defina um único esquema para seus dados que pode ser usado tanto no servidor quanto no cliente, garantindo consistência e segurança de tipos.

Passo 1: Defina um Esquema Zod

Vamos definir um esquema para nosso formulário de fatura. Isso se torna a única fonte de verdade para o que constitui uma fatura válida.

            // app/lib/schemas.js
import { z } from 'zod';

export const InvoiceSchema = z.object({
  id: z.string(), // Teremos isso para atualizações, mas não para criação
  customerId: z.string({ invalid_type_error: 'Por favor, selecione um cliente.' }),
  amount: z.coerce
    .number()
    .gt(0, { message: 'Por favor, insira um valor maior que R$0.' }),
  status: z.enum(['pending', 'paid'], {
    invalid_type_error: 'Por favor, selecione um status para a fatura.',
  }),
  date: z.string(),
});

export const CreateInvoice = InvoiceSchema.omit({ id: true, date: true });
            

              
                Copy
              
            
          

Passo 2: Use o Esquema na sua Server Action

Agora, podemos substituir todas as nossas verificações manuais por uma única chamada ao nosso esquema Zod. O método `safeParse` do Zod retornará os dados validados ou um objeto de erro detalhado.

            // app/actions.js
'use server';

import { z } from 'zod';
import { CreateInvoice } from '@/app/lib/schemas';

export async function createInvoiceWithZod(prevState, formData) {
  // 1. Valide os campos do formulário usando Zod
  const validatedFields = CreateInvoice.safeParse({
    customerId: formData.get('customerId'),
    amount: formData.get('amount'),
    status: formData.get('status'),
  });

  // 2. Se a validação falhar, retorne os erros imediatamente.
  if (!validatedFields.success) {
    return {
      errors: validatedFields.error.flatten().fieldErrors,
      message: 'Campos Ausentes. Falha ao Criar Fatura.',
    };
  }

  // 3. Prepare os dados para inserção no banco de dados
  const { customerId, amount, status } = validatedFields.data;
  const amountInCents = amount * 100;
  const date = new Date().toISOString().split('T')[0];

  // 4. Insira os dados no banco de dados
  try {
    // await sql`...` sua consulta ao banco de dados aqui
    console.log('Fatura criada com sucesso com dados validados.');
  } catch (error) {
    return {
      message: 'Erro no Banco de Dados: Falha ao Criar Fatura.',
    };
  }

  // 5. Revalide e redirecione
  revalidatePath('/dashboard/invoices');
  redirect('/dashboard/invoices');
}
            

              
                Copy
              
            
          

Note como isso é muito mais limpo. A lógica de validação é declarativa e co-localizada em nosso arquivo de esquema. A responsabilidade da action agora é orquestrar a validação, o processamento de dados e a interação com o banco de dados. O método `flatten().fieldErrors` do Zod fornece um objeto perfeitamente estruturado que mapeia nomes de campos para um array de mensagens de erro, que é exatamente o que nosso componente de formulário precisa.

Melhores Práticas Críticas de Segurança para Server Actions

Usar uma biblioteca de validação é um passo gigantesco, mas a verdadeira segurança requer uma abordagem em várias camadas. Cada Server Action é um vetor de ataque em potencial.

1. Sempre Assuma Intenção Maliciosa

Nunca, jamais confie na entrada do usuário. Esta é a regra de ouro. Mesmo que seu código do lado do cliente envie dados perfeitos, um invasor pode usar ferramentas como `curl` ou Postman para enviar uma requisição criada manualmente diretamente para o seu endpoint da Server Action. Sua lógica do lado do servidor é sua única defesa confiável.

• Valide Tudo: Valide não apenas o formato, mas também a lógica de negócios. Este usuário tem permissão para criar uma fatura para *este* cliente? O valor está dentro de um intervalo razoável?
• Sanitize para a Saída: Embora o React escape dados automaticamente para prevenir XSS ao renderizar, se você estiver usando dados em outros contextos (ex: gerando e-mails, logs), esteja atento à sanitização para prevenir injeção de scripts nesses sistemas.

2. Autenticação e Autorização são Obrigatórias

Toda Server Action que realiza uma mutação (criar, atualizar, excluir) ou acessa dados protegidos deve verificar a identidade e as permissões do usuário.

Sempre inicie sua action com uma verificação de sessão:

            // app/actions.js
'use server';

import { auth } from '@/auth'; // Supondo que você use NextAuth.js ou similar
import { sql } from '@vercel/postgres';

export async function deleteInvoice(id) {
  const session = await auth();
  if (!session?.user) {
    // Ou lance um erro
    return { message: 'Autenticação necessária.' };
  }

  // Verificação de autorização: este usuário tem permissão para excluir?
  // Isso pode envolver a verificação de papéis ou propriedade.
  const userRole = session.user.role;
  if (userRole !== 'admin') {
    return { message: 'Ação não autorizada.' };
  }

  try {
    await sql`DELETE FROM invoices WHERE id = ${id}`;
    revalidatePath('/dashboard/invoices');
    return { message: 'Fatura Excluída.' };
  } catch (error) {
    return { message: 'Erro no Banco de Dados: Falha ao Excluir Fatura.' };
  }
}
            

              
                Copy
              
            
          

3. Proteção Contra CSRF (Cross-Site Request Forgery)

Ataques CSRF enganam um usuário logado para que ele envie, sem saber, uma requisição maliciosa para sua aplicação. Felizmente, frameworks como o Next.js têm proteção CSRF integrada para Server Actions usando uma combinação de técnicas, incluindo cookies de envio duplo e verificação de origem. Embora isso seja tratado para você, é crucial estar ciente e garantir que você não crie vulnerabilidades inadvertidamente ao configurar mal o seu ambiente.

4. Implemente Limitação de Taxa (Rate Limiting)

Um usuário mal-intencionado ou um bot poderia enviar spam para seus formulários, tentando forçar um login, esgotar suas conexões com o banco de dados ou encher seu sistema com dados inúteis. Implementar limitação de taxa (rate limiting) em Server Actions críticas é essencial.

Você pode usar serviços como o Upstash Rate Limiting ou implementar sua própria lógica usando um armazenamento de chave-valor como o Redis. A chave é tipicamente o endereço IP do usuário ou o ID do usuário.

            import { Ratelimit } from '@upstash/ratelimit';
import { Redis } from '@upstash/redis';

// Crie um novo limitador de taxa, permitindo 5 requisições por 10 segundos
const ratelimit = new Ratelimit({
  redis: Redis.fromEnv(),
  limiter: Ratelimit.slidingWindow(5, '10 s'),
});

export async function sensitiveAction(formData) {
  const ip = headers().get('x-forwarded-for'); // Ou obtenha o ID do usuário da sessão
  const { success } = await ratelimit.limit(ip);

  if (!success) {
    return { message: 'Muitas requisições. Por favor, tente novamente mais tarde.' };
  }

  // ... resto da lógica da action
}
            

              
                Copy
              
            
          

Considerações Globais e de Acessibilidade

Construir para uma audiência global requer pensar além da simples implementação técnica.

Internacionalização (i18n) de Mensagens de Erro

Codificar mensagens de erro em inglês não é ideal para uma aplicação global. Uma abordagem melhor é fazer com que sua Server Action retorne *códigos* ou *chaves* de erro.

            // Na action
if (!validatedFields.success) {
  // ...
  return { errors: { customerId: ['error.customer.required'] } };
}

// No componente de cliente, usando uma biblioteca como 'react-i18next'
import { useTranslation } from 'react-i18next';

function MyForm() {
  const { t } = useTranslation();
  const [state, dispatch] = useFormState(...);

  // ...
  {state.errors?.customerId && 
    
{t(state.errors.customerId[0])}
}
}
            

              
                Copy
              
            
          

Isso separa sua lógica de validação da sua apresentação e permite que seu front-end lide com as traduções de forma transparente.

Acessibilidade (a11y)

Ao exibir erros, garanta que eles sejam acessíveis para usuários de tecnologias assistivas. Associe as mensagens de erro aos seus campos de formulário correspondentes usando o atributo `aria-describedby`.

            

  Nome do Cliente
  
  

    {state.errors?.customerName &&
      state.errors.customerName.map((error) => (
        
{error}
      ))}
  

            

              
                Copy
              
            
          

O atributo `aria-live="polite"` garantirá que os leitores de tela anunciem a mensagem de erro quando ela aparecer.

Conclusão: Uma Nova Era de Responsabilidade

As React Server Actions são uma ferramenta poderosa que agiliza o desenvolvimento full-stack, aproximando a lógica do servidor da UI como nunca antes. Esse poder, no entanto, exige uma mentalidade disciplinada e focada na segurança.

Ao aproveitar hooks como `useFormState` e `useFormStatus`, podemos criar formulários aprimorados progressivamente com uma excelente experiência do usuário. Ao integrar bibliotecas robustas de validação de esquemas como Zod, podemos escrever uma lógica de validação limpa, de fácil manutenção e com segurança de tipos. E ao aderir aos princípios fundamentais de segurança — autenticação, autorização, limitação de taxa e sempre validar no servidor — podemos construir aplicações que não são apenas elegantes e eficientes, mas também resilientes e seguras.

Trate cada Server Action como um endpoint de API público. Valide suas entradas, verifique suas permissões e trate seus erros com elegância. Ao fazer isso, você pode aproveitar com confiança todo o potencial deste novo e empolgante capítulo no desenvolvimento React.